package com.weijian.service;


import com.weijian.common.exception.SqlExecutionException;
import com.weijian.dto.data.QueryResult;
import com.weijian.dto.data.TableInfo;
import com.weijian.dto.data.TableStructure;

import java.util.List;

/**
 * 数据分析数据源服务接口
 * 提供对独立数据分析数据库的SQL查询能力
 */
public interface AnalysisDataSourceService {

    /**
     * 执行SQL查询
     * 执行指定的SQL查询语句并返回结构化结果
     *
     * @param sql SQL查询语句(SELECT语句)
     * @return 查询结果,包含列名、数据行、行数和执行时间
     * @throws SqlExecutionException 当SQL执行失败时抛出
     */
    QueryResult executeQuery(String sql) throws SqlExecutionException;

    /**
     * 执行带参数的SQL查询
     * 使用参数化查询防止SQL注入,提供更安全的查询方式
     *
     * @param sql    SQL查询语句,使用?作为参数占位符
     * @param params SQL参数值,按照占位符顺序提供
     * @return 查询结果,包含列名、数据行、行数和执行时间
     * @throws SqlExecutionException 当SQL执行失败时抛出
     */
    QueryResult executeQuery(String sql, Object... params) throws SqlExecutionException;

    /**
     * 测试数据库连接
     * 检查数据分析数据库是否可以正常连接
     *
     * @return true表示连接正常,false表示连接失败
     */
    boolean testConnection();

    /**
     * 获取数据库中所有表的列表
     * 返回当前数据库中所有用户表的基本信息
     *
     * @return 表信息列表
     * @throws SqlExecutionException 当查询失败时抛出
     */
    List<TableInfo> getTables() throws SqlExecutionException;

    /**
     * 获取指定表的结构信息
     * 返回表的基本信息和所有列的详细信息
     *
     * @param tableName 表名
     * @return 表结构信息,包含表信息和列信息列表
     * @throws SqlExecutionException 当查询失败时抛出
     */
    TableStructure getTableStructure(String tableName) throws SqlExecutionException;
}
